home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / tjgold.zip / INSTALL.004 / FGUSER18.TXT < prev    next >
Text File  |  1995-05-29  |  15KB  |  385 lines
  1.                                Managing Strings
  2.  
  3.                                          "When gold argues the cause,
  4.                                           eloquence is impotent."
  5.                                                    Pubilius Syrus
  6.                                                   "Moral Sayings"
  7.                                                    1st Century BC
  8.  
  9. Introduction
  10.  
  11.           The GOLDSTR unit contains all the string management routines
  12.      needed to support any sophisticated DOS application. The unit
  13.      includes the following:
  14.  
  15.           Functions which make predefined adjustments to strings
  16.           Support for character testing and conversion
  17.           Functions which convert numbers to and from strings
  18.           String encryption to protect your data
  19.           String Adjustment
  20.  
  21.           Gold defines a user input with three basic variables: the
  22.      keystroke or mouse action, the mouse X coordinate and the mouse Y
  23.      coordinate. These three variables are defined in the KeyVars record
  24.      as LastKey, LastX and LastY.
  25.  
  26.      Replicate(N : byte; Character:char): string;
  27.  
  28.           Constructs a string of repeated characters. This routine uses
  29.      memory moves which are much faster than a for loop.
  30.  
  31.      PicFormat(Input,Picture:string;Pad:char;RightJustify:boolean):
  32.                                                               string;
  33.  
  34.           Returns a formatted string using the format characters '!@*#'.
  35.      See chapter 16 for a complete discussion on formatting characters.
  36.  
  37.      TruncFormat(Input:string;Start,Len:byte; Pad:char):string;
  38.  
  39.           Truncates (or expands) a string beginning at a specified
  40.      character position. If Start is greater than 1, character positions
  41.      less than Start are truncated. If Len is greater than the remaining
  42.      string, then the remaining string is padded to a length of Len
  43.      using the Pad character.
  44.  
  45.      Squeeze(L:char;Str:string;Width:byte): string;
  46.  
  47.           Squeezes a string to the length defined by width, removing
  48.      characters from the beginning or the end of the string if
  49.      necessary. If  'L' is passed then the left portion of the string is
  50.      retained, otherwise the right portion is retained.
  51.  
  52.           The returned string appears as if the string doesn't fit in
  53.      the space allocated. This is accomplished by adding the squeeze
  54.      character string. GoldStr defines a variable, StrVars.SqzChars
  55.      which by default is a double dot string (..).
  56.  
  57.      FirstCapitalPos(Str:string): byte;
  58.  
  59.           Returns the position of the first capital letter contained in
  60.      the passed string. A zero is returned if no capital letters are
  61.      encountered.
  62.  
  63.      FirstCapital(Str:string): char;
  64.  
  65.           Returns the first capital letter encountered in the passed
  66.      string. If no capital letters are encountered then a null character
  67.      is returned.
  68.  
  69.      PadLeft(Str:string;Size:byte;ChPad:char):string;
  70.  
  71.           Left justifies the passed string, padding with ChPad, if
  72.      necessary, to a length indicated by size.
  73.  
  74.      PadCenter(Str:string;Size:byte;ChPad:char):string;
  75.  
  76.           Centers the passed string within a string, padding with ChPad,
  77.      if necessary, to a length indicated by size.
  78.  
  79.      PadRight(Str:string;Size:byte;ChPad:char):string;
  80.  
  81.           Right justifies the passed string, padding with ChPad, if
  82.      necessary, to a length indicated by size.
  83.  
  84.      Pad(PadJust:gJust;Str:string;Size:byte;ChPad:char):string;
  85.  
  86.           If your application requires that the justification be
  87.      determined at runtime then this is the routine for you. Pad
  88.      incorporates all three by allowing you to specify the proper
  89.      justification, Left, Right, or Center.
  90.  
  91.      TabSubStr(Source:string; TabCount:byte):string;
  92.  
  93.           This routine permits simple parsing of a delimited string
  94.      using a single delimiter. It is used extensively within the toolkit
  95.      itself. TabSubStr extracts the string immediately before the
  96.      delimiter defined by TabCount.
  97.  
  98.           The GoldStr unit defines a global variable called
  99.      StrVars.TabBreak which by default is the vertical split bar.
  100.  
  101.      An example of using TabSubStr follows:
  102.  
  103.           const UserStr = 'Silver|Bronze|Gold|Brass';
  104.  
  105.           var SubStr: String;
  106.           begin
  107.              SubStr := TabSubStr(UserStr,3);
  108.              { SubStr will now be 'Gold' }
  109.           end;
  110.  
  111.      Last(N:byte;Str:string):string;
  112.  
  113.           Extracts the last part of a string beginning at a specified
  114.      position. If N is greater than the length of the passed string,
  115.      only the string is returned.
  116.  
  117.      First(N:byte;Str:string):string;
  118.  
  119.           Extracts the first part of a string. Beginning at position 1,
  120.      First returns N number of characters. If N is greater than the
  121.      length of the passed string, the entire string is returned.
  122.  
  123.      SetUpper(Str:string):string;
  124.  
  125.           Converts all alpha characters of the passed string to upper
  126.      case.
  127.  
  128.      SetLower(Str:string):string;
  129.  
  130.           Converts all alpha characters of the passed string to lower
  131.      case.
  132.  
  133.      SetProper(Str:string):string;
  134.  
  135.           Converts the first character of each word in the passed string
  136.      to upper case while the remaining characters are converted to lower
  137.      case.
  138.  
  139.      AdjCase(NewCase:gCase;Str:string):string;
  140.  
  141.           Returns an appropriately adjusted string. If your application
  142.      requires that the case of words be modified during execution,
  143.      AdjCase incorporates all three by allowing you to specify the
  144.      proper case; Upper, Lower or Proper. The type gCase defines one
  145.      other enumeration called Leave, which does nothing to the passed
  146.      string. Just leaves it unaltered.
  147.  
  148.      OverType(N:byte;StrS,StrT:string):string;
  149.  
  150.           Places one string "on top of" another string and overlays the
  151.      underlying characters. The function is passed three parameters; the
  152.      character position in the target string to start the overtyping,
  153.      the source string, and the target string.
  154.  
  155.      Strip(L,C:char;Str:string):string;
  156.  
  157.           Returns the string with a specific character C removed. The
  158.      function is passed three parameters; a character to indicate which
  159.      part of the string to strip, the character to strip, and the source
  160.      string. The strip can be performed on the left of the string by
  161.      specifying the L parameter with one of the following characters:
  162.  
  163.           'L' - Removes the leftmost specified characters.
  164.           'R' - Removes the rightmost specified characters.
  165.           'B' - Removes the leftmost and rightmost characters.
  166.           'A' - Removes all specified characters.
  167.  
  168.      LastPos(C:char;Str:string):byte;
  169.  
  170.           Returns a byte indicating the position of the last occurrence
  171.      of a character in a string. If the character is not found, a zero
  172.      is returned. The function is passed two parameters; a character to
  173.      search for, and the source string.
  174.  
  175.      PosAfter(C:char;Str:string;Start:byte):byte;
  176.  
  177.           Returns a byte indicating the position of the first occurrence
  178.      of a character, starting from a specified position in the string.
  179.      If the character is not found, or if Start is greater than the
  180.      length of the passed string, a zero is returned.
  181.  
  182.      LastPosBefore(C:char;Str:string;Last:byte):byte;
  183.  
  184.           Returns a byte indicating the position of the last occurrence
  185.      of a character, up to a specified part fo the string. The search
  186.      begins at character 1 and continues through the character specified
  187.      by Last. A zero is returned if the character is not found.
  188.  
  189.      NthPos(Nth:byte;St,Src:string): byte;
  190.  
  191.           Returns a byte indicating the position of the Nth occurrence
  192.      of a substring in a string. A zero is returned if the substring is
  193.      not found.
  194.  
  195.      PosWord(Wordno:byte;Str:string):byte;
  196.  
  197.           Returns the character position of a specified word in a
  198.      string.
  199.  
  200.      WordCnt(Str:string):byte;
  201.  
  202.           Counts and returns the number of words contained in a string.
  203.  
  204.      ExtractWords(StartWord,NoWords:byte;Str:string):string;
  205.  
  206.           Beginning at a specified word, extracts a specific number of
  207.      words from a string.
  208.  
  209. String and Number Conversions
  210.  
  211.           The following three functions should be used to test whether a
  212.      string can be successfully converted to its numerical equivalent:
  213.  
  214.      ValidInt(Str:string):boolean;
  215.  
  216.           Returns TRUE if the string can be converted to an integer.
  217.  
  218.      ValidHEXInt(Str:string):boolean;
  219.  
  220.           Returns TRUE if the source string represents a valid
  221.      hexadecimal number.
  222.  
  223.      ValidReal(Str:string):boolean;
  224.  
  225.           Returns TRUE if the string can be converted to a real.
  226.  
  227.      The following functions enable string and number conversion:
  228.  
  229.      StrToInt(Str:string):integer;
  230.  
  231.           Converts a valid numeric string to an integer value. If the
  232.      string does not represent an integer value, a zero is returned, and
  233.      an error code of 1004 is assigned to LastStrError.
  234.  
  235.      StrToLong(Str:string):Longint;
  236.  
  237.           Converts a valid numeric string to a longint value. If the
  238.      string does not represent a longint value, a zero is returned, and
  239.      an error code of 1002 is assigned to LastStrError.
  240.  
  241.      IntToStr(Number:longint):string;
  242.  
  243.           Converts a whole number to its string equivalent.
  244.  
  245.      StrToReal(Str:string):extended;
  246.  
  247.           Converts a valid real string to a real. If the string does not
  248.      represent a real value, a zero is returned, and an error code of
  249.      1003 is assigned to LastStrError.
  250.  
  251.      RealToStr(Number:extended;Decimals:byte):string;
  252.  
  253.           Converts a real to its string equivalent. If the number of
  254.      decimal places is passed as FLOATING (a constant), the function
  255.      will return only the significant digits.
  256.  
  257.      IntToHEXStr(Number:longint;Width:integer):string;
  258.  
  259.           Returns a string representing the value of a hexadecimal
  260.      number.
  261.  
  262.      HEXStrToLong(Str:string):longint;
  263.  
  264.           Converts a hexadecimal string and returns a longint. If the
  265.      string is not a valid hex number, a zero is returned, and an error
  266.      code of 1002 is assigned to LastStrError.
  267.  
  268.      RealToSciStr(Number:extended; D:byte):string;
  269.  
  270.           Returns a real number converted to a scientific notation
  271.      string. The second parameter identifies the number of decimal
  272.      places.
  273.  
  274.      NthNumber(InStr:string;Nth:byte) : char;
  275.  
  276.           This function returns a number in character form. Gold
  277.      searches InStr, counting each occurrence of a number character.
  278.      When N number characters have been counted, the value of the Nth
  279.      character is returned. For example, if the string '02/20/48' is
  280.      passed, and the N parameter is passed as 5, the character '4' would
  281.      be returned, i.e. the fifth number in the string has a value of 4.
  282.  
  283. Character Evaluation and Case Conversion
  284.  
  285.      IsUpper(K:word): boolean;
  286.  
  287.           Returns TRUE if the value represented by K is an upper case
  288.      character.
  289.  
  290.      IsLower(K:word): boolean;
  291.  
  292.           Returns TRUE if the value represented by K is a lower case
  293.      character.
  294.  
  295.      IsDigit(K:word): boolean;
  296.  
  297.           Returns TRUE if the value represented by K is a digit ranging
  298.      from 0 to 9.
  299.  
  300.      IsLetter(K:word): boolean;
  301.  
  302.           Returns TRUE if the value represented by K is an alpha
  303.      character.
  304.  
  305.      IsPunctuation(K:word): boolean;
  306.  
  307.           Returns TRUE if the value represented by K is a punctuation
  308.      character.
  309.  
  310.      GetUpCase(Ch:char):char;
  311.  
  312.           Converts the character represented by Ch to its upper case
  313.      equivalent.
  314.  
  315.      GetLoCase(Ch:char):char;
  316.  
  317.           Converts the character represented by Ch to its lower case
  318.      equivalent.
  319.  
  320.      CapitalWord(W:word):word;
  321.  
  322.           Converts the character represented by W to uppercase and
  323.      returns the word value of the capital letter.
  324.  
  325. String Encryption
  326.  
  327.           Data encryption has been the study of mathematicians and R & D
  328.      teams since man determined that it was necessary to protect certain
  329.      information. We would never attempt to compete with any of the
  330.      highly complex methods of data encryption that are employed today.
  331.      However, we have implemented an extremely simple but useful form of
  332.      encryption. Each character of the passed string is encrypted using
  333.      the XOR operator in conjunction with an encryption code. The
  334.      variable StrVars.EncryptionCode, which is of type word, affects the
  335.      content of the encrypted string. By default the encryption code is
  336.      134, but may be changed.
  337.  
  338.           If you are going to store the final encrypted strings in text
  339.      files, it is important to keep the value of StrVars.EncryptionCode
  340.      between 128 and 255. Values between 0 and 127 occasionally produce
  341.      a Ctrl-Z or EOF character. This produces a premature end-of-file
  342.      when the text file is being retrieved from disk.
  343.  
  344.      EnCode(Str: string): string;
  345.  
  346.           Converts the passed, readable string, to an unreadable string.
  347.  
  348.      DeCode(Str: string): string;
  349.  
  350.           Converts the passed, unreadable string, to a readable string.
  351.  
  352.           One valuable use of string encryption is to store encoded
  353.      constants in a program, such as passwords. You can compare the
  354.      user's input to the function call, DeCode(<constant>). The
  355.      probability of someone locating and decoding your embedded password
  356.      in the final, compiled program is, at best, slim to none. The
  357.      encoded constants would be generated by another small utility
  358.      program that you would write.
  359.  
  360. Miscellaneous
  361.  
  362.           Listed below are some other string management functions that
  363.      couldn't find a home anywhere else:
  364.  
  365.      CharCount(Ch:Char;Str:string):byte;
  366.  
  367.           Returns the total number of times Ch occurs in Str.
  368.  
  369.      WidestLine(Str:string):byte;
  370.  
  371.           Searches for the embedded line break character and returns the
  372.      length of the longest line-element. The line break character is
  373.      defined as a global  variable, StrVars.LineBreak. Its default is
  374.      the vertical split bar.
  375.  
  376.      LineCount(Str:string):byte;
  377.  
  378.           A bit different from the obvious appearance, LineCount returns
  379.      the number of elements contained in a <LineBreak> delimited string.
  380.  
  381.      LastStrError: integer;
  382.  
  383.           Returns the code of the last error generated by a GoldStr
  384.      routine.
  385.